Handle unknown event types gracefully instead of crashing by Alan4506 · Pull Request #680 · smithy-lang/smithy-python

Alan4506 · 2026-04-07T16:01:56Z

Background

The Smithy spec (streaming.html#client-behavior) states:

"Adding new events to an event stream union is considered a backward compatible change; clients SHOULD NOT fail when an unknown event is received."

Currently, in smithy-aws-event-stream deserializers.py, EventDeserializer.read_struct() does a hard dictionary lookup (schema.members[member_name]) which raises KeyError when the service sends an event type not present in the generated model. So we have to add some logic to handle unknown event types.

Additionally, although smithy-python automatically creates unknown variants for streams, these variants only have a tag field unlike normal events that have a value field. When AWSEventReceiver.receive() calls getattr(result, "value") without a default, it raises AttributeError for unknown variants.

These were discovered during Q Business Chat streaming integration testing. The service sends intermediateGroupEvent and intermediateMessageEvent events not in any published SDK model, causing the async for event in output_stream loop to crash.

Reference implementations in other Smithy SDKs:

Both smithy-java and smithy-rs (Rust) already handle unknown event types gracefully:

smithy-java (TestEventStream.java): Generates a $Unknown(String memberName) record for each event stream union. The builder has an $unknownMember(String memberName) method that the deserializer calls when it encounters an unrecognized event type. The unknown variant preserves the event type name.
smithy-rs (EventStreamUnmarshallerGenerator.kt): The generated unmarshaller has an _unknown_variant match arm that returns Ok(UnmarshalledMessage::Event(Output::Unknown)) for client targets. Unlike Java, the Rust unknown variant does not preserve the event type name.

This PR follows the smithy-java approach of preserving the event type name in the unknown variant's tag field, so users can identify which unmodeled event was received (e.g., ChatOutputStreamUnknown(tag="intermediateGroupEvent")).

Description of Changes

smithy-aws-event-stream (deserializers.py): When member_name is not in schema.members, construct a synthetic Schema with member_index=-1 and call the consumer, which triggers the generated case _: branch in UnionGenerator.java.
smithy-python codegen (UnionGenerator.java): The case _: branch (previously just logging) now also constructs the per-union unknown variant with the event type name as tag.
smithy-aws-event-stream (aio/__init__.py): Change getattr(result, "value") to getattr(result, "value", None) to prevent AttributeError on unknown variants.

Testing

Regenerated all existing clients locally and all their integration tests passed. Also, verified with Q Business Chat streaming — unknown events (intermediateGroupEvent, intermediateMessageEvent) are now handled gracefully instead of crashing. Users can identify unknown events via isinstance and access the event type name:

from aws_sdk_qbusiness.models import ChatOutputStreamUnknown

async for event in output_stream:
    if isinstance(event, ChatOutputStreamUnknown):
        print(f"Unknown event: {event.tag}")

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

…rashing

alexgromero · 2026-04-07T16:54:13Z

packages/smithy-aws-event-stream/src/smithy_aws_event_stream/_private/deserializers.py

+                        logger.debug(
+                            "Unknown event type: %s", member_name
+                        )
+                        from smithy_core.shapes import ShapeID


Should we move the ShapeID import to the top with the other smithy_core.shapes imports? Doesn't seem like we need it inline here.

alexgromero · 2026-04-07T17:00:20Z

packages/smithy-aws-event-stream/src/smithy_aws_event_stream/_private/deserializers.py

We should add unit tests in test_deserializers.py for the unknown event handling path.

Also, the test fixture EventStreamDeserializer._consumer still raises SmithyError in the default case. Should that be updated to match the new behavior?

alexgromero · 2026-04-07T17:41:54Z

packages/smithy-aws-event-stream/src/smithy_aws_event_stream/aio/__init__.py

        result = self._deserializer(deserializer)
        logger.debug("Successfully deserialized event: %s", result)
-        if isinstance(getattr(result, "value"), Exception):
+        if isinstance(getattr(result, "value", None), Exception):


Suggested change

if isinstance(getattr(result, "value", None), Exception):

value = getattr(result, "value", None)

if isinstance(value, Exception):

Small readability suggestion (non-blocking): since only some variants have value, maybe assign it first and check that instead so it's a bit clearer and avoids looking up value twice here and in the raise statement.

jonathan343 · 2026-04-10T16:36:26Z

packages/smithy-aws-event-stream/tests/unit/_private/test_deserializers.py

+    message = EventMessage(
+        headers={
+            ":message-type": "event",
+            ":event-type": "intermediateGroupEvent",


Suggested change

":event-type": "intermediateGroupEvent",

":event-type": "unmodeledEvent",

jonathan343 · 2026-04-10T16:36:36Z

packages/smithy-aws-event-stream/tests/unit/_private/test_deserializers.py

+    deserializer = EventDeserializer(event=source, payload_codec=JSONCodec())
+    result = EventStreamDeserializer().deserialize(deserializer)
+    assert isinstance(result, EventStreamUnknown)
+    assert result.tag == "intermediateGroupEvent"


Suggested change

assert result.tag == "intermediateGroupEvent"

assert result.tag == "unmodeledEvent"

jonathan343 · 2026-04-10T16:37:20Z

packages/smithy-aws-event-stream/tests/unit/_private/test_deserializers.py

    EventStreamDeserializer,
    EventStreamErrorEvent,
    EventStreamOperationInputOutput,
+    EventStreamUnknown,


Suggested change

EventStreamUnknown,

EventStreamUnknownEvent,

I did not add "Event" at the end because the generated code does not have "Event" suffix after "Unknown".

jonathan343 · 2026-04-10T16:37:34Z

packages/smithy-aws-event-stream/tests/unit/_private/test_deserializers.py

+    assert source is not None
+    deserializer = EventDeserializer(event=source, payload_codec=JSONCodec())
+    result = EventStreamDeserializer().deserialize(deserializer)
+    assert isinstance(result, EventStreamUnknown)


Suggested change

assert isinstance(result, EventStreamUnknown)

assert isinstance(result, EventStreamUnknownEvent)

I did not add "Event" at the end because the generated code does not have "Event" suffix after "Unknown".

jonathan343 · 2026-04-10T16:37:51Z

packages/smithy-aws-event-stream/tests/unit/_private/__init__.py



+UNKNOWN_EVENT_CASE = (
+    EventStreamUnknown(tag="intermediateGroupEvent"),


nit - this event type is specific to QBusiness, we should use something generic:

Suggested change

EventStreamUnknown(tag="intermediateGroupEvent"),

EventStreamUnknownEvent(tag="unmodeledEvent"),

jonathan343 · 2026-04-10T16:44:50Z

packages/smithy-aws-event-stream/tests/unit/_private/__init__.py

    | EventStreamBlobPayloadEvent
    | EventStreamErrorEvent
-    | EventStreamUnknownEvent
+    | EventStreamUnknown


Suggested change

| EventStreamUnknown

| EventStreamUnknownEvent

I modified this because the generated code does not have "Event" suffix after "Unknown".

jonathan343 · 2026-04-10T16:47:01Z

codegen/core/src/main/java/software/amazon/smithy/python/codegen/generators/UnionGenerator.java

                            ${4C|}
                            case _:
                                logger.debug("Unexpected member schema: %s", schema)
+                                self._set_result($5L(tag=schema.member_name or ""))


Why use tag=schema.member_name or "" here instead of something like tag=schema.expect_member_name()?

jonathan343 · 2026-04-10T17:03:27Z

codegen/core/src/main/java/software/amazon/smithy/python/codegen/generators/UnionGenerator.java

We should remove this TODO

jonathan343 · 2026-04-10T17:06:48Z

packages/smithy-aws-event-stream/src/smithy_aws_event_stream/_private/deserializers.py

-                        member_schema, headers
-                    )
-                    consumer(member_schema, message_deserializer)
+                    member_schema = schema.members.get(member_name)


I'm thinking we can consolidate this logic into a member_schema = self._resolve_member_schema(schema, member_name) method to make this a bit cleaner.

jonathan343 · 2026-04-10T17:10:30Z

packages/smithy-aws-event-stream/src/smithy_aws_event_stream/_private/deserializers.py

+                        # member_name and a member_index of -1 so the
+                        # generated default branch constructs the unknown
+                        # variant with the correct tag.
+                        logger.debug("Unknown event type: %s", member_name)


This logic seems odd, why can't we do something like:

def _resolve_member_schema(self, schema: Schema, member_name: str) -> Schema: if member_schema := schema.members.get(member_name): return member_schema logger.debug( "Received unmodeled event stream member %s for union %s", member_name, schema.id, ) return Schema.member( id=schema.id.with_member(member_name), target=schema, index=-1, )

This keeps the real event payload/headers intact and lets the generated union fallback produce *Unknown(tag=...) in one place, instead of special-casing unknown events in the runtime with a fake {} document.

fix(event-stream): Handle unknown event types gracefully instead of c…

78a70a5

…rashing

Alan4506 requested a review from a team as a code owner April 7, 2026 16:01

Alan4506 changed the title ~~Fix EvenHandle unknown event types gracefully instead of crashing~~ Handle unknown event types gracefully instead of crashing Apr 7, 2026

alexgromero reviewed Apr 7, 2026

View reviewed changes

Fix format issue and add unit tests for handling unknown events

e8f84ce

jonathan343 requested changes Apr 10, 2026

View reviewed changes

Address PR review: refactor unknown event handling

df69da0

	if isinstance(getattr(result, "value", None), Exception):
	value = getattr(result, "value", None)
	if isinstance(value, Exception):

	":event-type": "intermediateGroupEvent",
	":event-type": "unmodeledEvent",

	assert result.tag == "intermediateGroupEvent"
	assert result.tag == "unmodeledEvent"

	assert isinstance(result, EventStreamUnknown)
	assert isinstance(result, EventStreamUnknownEvent)



		UNKNOWN_EVENT_CASE = (
		EventStreamUnknown(tag="intermediateGroupEvent"),

	EventStreamUnknown(tag="intermediateGroupEvent"),
	EventStreamUnknownEvent(tag="unmodeledEvent"),

Conversation

Alan4506 commented Apr 7, 2026

Background

Description of Changes

Testing

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexgromero Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

alexgromero Apr 7, 2026 •

edited

Loading